EnvoyARexx - Version 1.0

ARexx-service for Envoy

by Alexander Stirmlinger

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1995 Alexander Stirmlinger All rights of the program, files and documents belong completely to the author. The contents of the archive must not be changed in any way. No files may be added or deleted to/from the archive. You may charge a fee to recover distribution costs. The fee for diskette distribution may not be more than the cost to obtain a public domain diskette from Fred Fish. Commercial distribution and usage is only allowed with a written permission from the author.

1 Copyright and legal information

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1995 Alexander Stirmlinger

All rights of the program, files and documents belong completely to the author. The contents of the archive must not be changed in any way. No files may be added or deleted to/from the archive.

You may charge a fee to recover distribution costs. The fee for diskette distribution may not be more than the cost to obtain a public domain diskette from Fred Fish.

Commercial distribution and usage is only allowed with a written permission from the author.

  THERE IS NO WARRANTY FOR THE PROGRAMS, TO THE EXTENT PERMITTED
BY APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAMS "AS
IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAMS IS
WITH YOU.  SHOULD THE PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE
COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
REDISTRIBUTE THE PROGRAMS AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
THE PROGRAMS (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAMS TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.

2 EnvoyARexx 1.0

2 Overview

The purpose of EnvoyARexx is to transmit ARexx-commands (and thus execute whole ARexxscripts) over an Envoy network.

EnvoyARexx is able to create ARexx-ports on the local machine. Any incoming message will be converted to an Envoy-transaction and sent to the appropriate remote machine. The service running on the remote will convert the transaction to an ARexx-message and forward it to the ARexx-port of the real application. The result of the messages (returned by the application) will be converted back to an Envoy-transaction and replied to the local machine. The library on the local machine will convert the result for use within the ARexx-message and replies the message. See also Chapter 3 [Archive overview], Page 5.

Additionally, you can ’connect’ to the COMMAND-’port’^{1} of a remote machine. Thus, you can easily run commands on a remote machine in the network.

1 This port isn’t actually a port, but can be accessed just like a port by ARexx-scripts.

A diagram may elucidate thoughts:

                       <- Function-calls
-----       rexxsys.library  <---------->    ARexx-scripts
|              |               Results ->       |
|   Function-  |                                |
|      calls   |  Results               Results | RexxMessages
|              |                                |
|              |               Results ->       |
Local      |      envoyarexx.library <----------> emulated ARexx-port
|              |       <- RexxMessages
|              |
|              |
|              |  Transactions
|              |
|            Envoy
-----             |
               |
            Network
               |
-----             |
|            Envoy
|              |
|              |  Transactions
|              |
|              |          RexxMessages ->
Remote     |      envoyarexx.service <----------> ARexx-port ('host')
|                      <- Results               |
|                                               |
-----                                         Application

3 Archive overview

• ‘envoyarexx.library’: ARexx function-library. Interface between ARexx and Envoy. Adds functions to ARexx when added to your system. Creates local ARexx-ports and forwards incoming ARexx-messages, receives the results from the remoted machines and sends them back to their reply-port. In the network-language you would call this library a client.

• ‘envoyarexx.service’: Envoy-alike service. Receives messages from a client, converts them to ARexx-messages an forwards them to the desired destination port. Sends back the result to the appropriate client. This Envoy-service is a server.

• ‘ConnectHost’: Creates a communication-path from the local envoyarexx.library to a remote envoyarexx.service. Opens an ARexx-port on the local machine, ready to receive and forward ARexx-messages.^{1}

• ‘DisConnectHost’: Removes a commnuication-path which was previously created by Dis-ConnectHost or by the appropriate ARexx-function of the library. Causes the envoyarexx.library to close the local ARexx-port.

• ‘Install_EnvoyARexx’: Automatic installation-script for EnvoyARexx.

• ‘EnvoyARexx.(guide|dvi)’: This manual. :-)

1 Please note that the envoyarexx.library provides compatible functions for ARexx-scripts.

6 EnvoyARexx 1.0

4 Installation

4.1 Automatic installation

For automatic installation of EnvoyARexx you can (should) use the script for Commodore’s Installer^{1}

4.2 Manual installation

If you want to install EnvoyARexx by hand (for what reason ever) you should copy:

• ‘envoyarexx.library’ in your LIBS: directory or wherever your scripts will find this file. The library is only needed on those machines which should run ARexx-scripts and/or run the ConnectHost command for example.

• ‘envoyarexx.service’ in your Envoy/Services directory. The service is only needed on targetmachines which actually run a ARexx-application. Please make sure to enable the service with the Services Configuration program.

• ‘ConnectHost’ and ‘DisConnectHost’ are the CLI-equivalents of the envoyarexx.library’s functions and thus only needed if you want to establish connections-paths ’by hand’ or via batchfiles. The ConnectHost and DisConnectHost commands need the envoyarexx.library.

• ‘EnvoyARexx.guide’ should - of course - be installed on every machine in your network, to come handy when you need it and to disturb you when you don’t. ;-)

1 Installer and Installer project icon (c) Copyright 1991-93 Commodore-Amiga, Inc. All Rights Reserved. Reproduced and distributed under license from Commodore.

INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE; NO WAR-RANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY OR RESPONSI-BILITY IS ASSUMED.

8 EnvoyARexx 1.0

5 Rexx function description

The following functions are implemented in the envoyarexx.library for usage within ARexxscripts. Please note that there are compatible^{1} CLI commands of these functions. See also Chapter 6 [CLI commands], Page 11.

Please remember that you have to CALL ADDLIB(’envoyarexx.library’, 0, -30), before you can use these functions within ARexx-scripts.

5.1 CONNECTHOST()

NAME CONNECTHOST() - Establish an EnvoyARexx-connection to a remote ARexx-port

SYNOPSIS CALL CONNECTHOST (Remote Machine,Remote ARexxPort,Local ARexxPort)

FUNCTION Creates a connection to a public port on a remote Amiga. Invokes the EnvoyARexxservice on the remote machine. No connection will be made, if the desired port can’t be found on the remote machine. After usage, the connection should be removed with the DISCONNECTHOST() function or the DisConnectHost CLI command.

EXAMPLE
                CALL CONNECTHOST ("RIKER","Ed")
                CALL CONNECTHOST ("CORE","COMMAND","COMMAND.CORE")
INPUTS

1. Remote Machine: Hostname of the remote Amiga.

2. Remote ARexxPort: Case-sensitive name of the public port you wish to connect to on the remote machine. The remote port must be findable via FindPort() and should be an ARexx-port, of course.

3. Local ARexxPort: Name of the appropriate public port that should be opened on the local Amiga. This argument is optional^{2} and defaults to the name of Remote ARexxPort. This name is case-sensitive, too.

RESULTS The ARexx-variable RC contains a specific error-code. See also Chapter 8 [Errorcodes and -messages], Page 15.

1 compatible means that it’s possible to remove connections with the CLI command DisConnectHost, which were originally established by using the ARexx-function CONNECTHOST() and vice versa.

2 However, this argument is required for COMMAND remote ports. You can never open a local port named COMMAND!

5.2 DISCONNECTHOST()

NAME DISCONNECTHOST() - Remove a connection to a remote ARexx-port

SYNOPSIS CALL DISCONNECTHOST (Local ARexxPort)

FUNCTION Closes the connection to the remote port, removes the local port from Exec’s list and frees it. Ports, that were not created by the CONNECTHOST() function or the DisConnectHost CLI command, won’t be touched.

EXAMPLE
                CALL DISCONNECTHOST ("Ed")
                CALL DISCONNECTHOST ("COMMAND.CORE")
INPUTS

1. Local ARexxPort: Case-sensitive name of the public port, whose connection to the remote port should be removed.

RESULTS The ARexx-variable RC contains a specific error-code. See also Chapter 8 [Errorcodes and -messages], Page 15.

6 CLI commands

The following CLI commands are provided for manual use or for usage within AmigaDOSscripts (batch-files). Compatible ARexx-functions are provided for use within ARexx-scripts. See also Chapter 5 [Rexx functions], Page 9.

6.1 ConnectHost

NAME ConnectHost - Establish an EnvoyARexx-connection to a remote ARexx-port TEMPLATE HOST/A,REMOTEPORT/A,LOCALPORT,LIBRARY/K FUNCTION ConnectHost acts just like the ARexx-function CONNECTHOST(). See also Sec-

tion 5.1 [CONNECTHOST()], Page 9.

INPUTS

1. HOST: Hostname of the remote Amiga in your network.

2. REMOTEPORT: Remote port to connect to.

3. LOCALPORT: Local name for the remote port.

4. LIBRARY: Path/filename of the envoyarexx.library. This is optional and useful if the library isn’t located in LIBS:.

6.2 DisConnectHost

NAME DisConnectHost - Remove a connection to a remote ARexx-port TEMPLATE LOCALPORT/A FUNCTION DisConnectHost acts just like the ARexx-function DISCONNECTHOST(). See also

Section 5.2 [DISCONNECTHOST()], Page 10.

INPUTS

1. LOCALPORT: Name of the local port to remove.

12 EnvoyARexx 1.0

7 First example

‘Example.earexx’ is a very simple example-script for EnvoyARexx. Please edit the remote machine’s name in the script before you start (rx Example.earexx) it.

The script first attempts to connect the the COMMAND-port of the remote, to run the Ed editor. After this, the script will send the quit command over the network. As a result, Ed will return a warning (20), which is returned over the network.

The output looks like this:

Connecting to RIKER port COMMAND
Disconnecting
Connecting to RIKER port Ed
 65 *-* ADDRESS 'LocalEd' 'q';
+++ Command returned 20
Disconnecting

14 EnvoyARexx 1.0

8 Errorcodes and errormessages

• 0 - no error: everything ok.

• 1 - unknown error: error occured, cause not known.

• 2 - destination port not found: the destination port was not found on the remote Amiga. Check if the application is running on the remote machine.

• 3 - no response space: size of the data to be replied exceeds the reply-buffer size.

• 4 - reply immediate: this is not really an error and should never occur.

• 5 - warning: generic warning.

• 10 - generic error

• 20 - fatal error

• 21 - no child-process: the library was unable to create the child-process.

• 22 - no messageport: unable to create messageport.

• 23 - no reply-messageport: unable to create reply-messageport.

• 24 - no host or service: service or host not found. May also indicate an Envoy-error.

• 25 - no file-handles: unable to open file-handles for SystemTagList().

• 26 - local port already exists

• 27 - port not found or alien: this error occurs if you try to disconnect a non-existing or a foreign port.

16 EnvoyARexx 1.0

9 Known bugs/problems

The following problem encountered so far: An ARexx-command, which doesn’t return a result ’immediately’ (a command that waits for user-input, for example) may cause an timeout-error, when the Envoy-timeout span is elapsed.

The timeout for RexxMessage-transactions is currently set to 200 seconds, which should be enough in most cases, but can be too much in some cases, anyway. Future versions of EnvoyARexx may provide a function to control the timeout by the ARexx-script dynamically.

18 EnvoyARexx 1.0

10 Author information

You can always reach me as follows:

Alexander Stirmlinger      Home: Weinbergweg 10
D-74831 Gundelsheim
Phone/Fax: ++49 - 62 69 - 89 92
EMail: alex@picard.unterland.de
(if this fails use
 alex@cybernet.de)

20 EnvoyARexx 1.0 Chapter 11: Acknowledgements 21

11 Acknowledgements

Thanks to those who made it happen:

• Jens Dreifeld: for providing me unparalleled service at cybernet.de.

• Robin Losch: for the envoyarexx.service-icon(s).

22 EnvoyARexx 1.0 Appendix A: History 23

Appendix A History

A.1 EnvoyARexx - Version 1.0

• First public release.

24 EnvoyARexx 1.0 Index 25

Index

A

Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Archive overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Author information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Automatic installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

B

Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

C

CLI commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ConnectHost. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 CONNECTHOST() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Copyright. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

D

DisConnectHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 DISCONNECTHOST() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

E

EMail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Errorcodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Errormessages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Example.earexx. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

F

FidoNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 First example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Function description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

H

History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

I

Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

K

Known bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

L

Legal information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

M

Manual installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

O

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

P

Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

R

Return-codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Rexx function description . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

S

Shell commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

T

The indispensable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

W

Warranty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

26 EnvoyARexx 1.0

Table of Contents

1 Copyright and legal information . . . . . . . . . . . . . . . . . . . . 1 2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3 Archive overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4.1 Automatic installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 Manual installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

5 Rexx function description . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5.1 CONNECTHOST() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.2 DISCONNECTHOST() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

6 CLI commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

6.1 ConnectHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6.2 DisConnectHost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

7 First example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 8 Errorcodes and errormessages. . . . . . . . . . . . . . . . . . . . . . 15 9 Known bugs/problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 10 Author information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 11 Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Appendix A History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

A.1 EnvoyARexx - Version 1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

ii EnvoyARexx 1.0